Expand description
faer
is a general-purpose linear algebra library for Rust, with a focus on high performance
for algebraic operations on medium/large matrices, as well as matrix decompositions.
Most of the high-level functionality in this library is provided through associated functions in
its vocabulary types: Mat
/MatRef
/MatMut
.
faer
is recommended for applications that handle medium to large dense matrices, and its
design is not well suited for applications that operate mostly on low dimensional vectors and
matrices such as computer graphics or game development. For those purposes, nalgebra
and
cgmath
may provide better tools.
§Basic usage
Mat
is a resizable matrix type with dynamic capacity, which can be created using
Mat::new
to produce an empty $0\times 0$ matrix, Mat::zeros
to create a rectangular
matrix filled with zeros, Mat::identity
to create an identity matrix, or Mat::from_fn
for the most generic case.
Given a &Mat<E>
(resp. &mut Mat<E>
), a MatRef<'_, E>
(resp. MatMut<'_, E>
) can be created by calling Mat::as_ref
(resp. Mat::as_mut
), which allow
for more flexibility than Mat
in that they allow slicing (MatRef::get
) and splitting
(MatRef::split_at
).
MatRef
and MatMut
are lightweight view objects. The former can be copied freely while the
latter has move and reborrow semantics, as described in its documentation.
More details about the vocabulary types can be found in each one’s module’s
documentation. See also: faer_entity::Entity
and complex_native
.
Most of the matrix operations can be used through the corresponding math operators: +
for
matrix addition, -
for subtraction, *
for either scalar or matrix multiplication depending
on the types of the operands.
§Example
use faer::{mat, scale, Mat};
let a = mat![
[1.0, 5.0, 9.0],
[2.0, 6.0, 10.0],
[3.0, 7.0, 11.0],
[4.0, 8.0, 12.0f64],
];
let b = Mat::<f64>::from_fn(4, 3, |i, j| (i + j) as f64);
let add = &a + &b;
let sub = &a - &b;
let scale = scale(3.0) * &a;
let mul = &a * b.transpose();
let a00 = a[(0, 0)];
§Matrix decompositions
faer
provides a variety of matrix factorizations, each with its own advantages and drawbacks:
§Cholesky decomposition
Mat::cholesky
decomposes a self-adjoint positive definite matrix $A$ such that
$$A = LL^H,$$
where $L$ is a lower triangular matrix. This decomposition is highly efficient and has good
stability properties.
An implementation for sparse matrices is also available.
§Bunch-Kaufman decomposition
Mat::lblt
decomposes a self-adjoint (possibly indefinite) matrix $A$ such that
$$P A P^\top = LBL^H,$$
where $P$ is a permutation matrix, $L$ is a lower triangular matrix, and $B$ is a block
diagonal matrix, with $1 \times 1$ or $2 \times 2$ diagonal blocks.
This decomposition is efficient and has good stability properties.
§LU decomposition with partial pivoting
Mat::partial_piv_lu
decomposes a square invertible matrix $A$ into a lower triangular
matrix $L$, a unit upper triangular matrix $U$, and a permutation matrix $P$, such that
$$PA = LU.$$
It is used by default for computing the determinant, and is generally the recommended method
for solving a square linear system or computing the inverse of a matrix (although we generally
recommend using a faer::linalg::solvers::Solver
instead of
computing the inverse explicitly).
An implementation for sparse matrices is also available.
§LU decomposition with full pivoting
Mat::full_piv_lu
Decomposes a generic rectangular matrix $A$ into a lower triangular
matrix $L$, a unit upper triangular matrix $U$, and permutation matrices $P$ and $Q$, such that
$$PAQ^\top = LU.$$
It can be more stable than the LU decomposition with partial pivoting, in exchange for being
more computationally expensive.
§QR decomposition
The QR decomposition (Mat::qr
) decomposes a matrix $A$ into the product
$$A = QR,$$
where $Q$ is a unitary matrix, and $R$ is an upper trapezoidal matrix. It is often used for
solving least squares problems.
An implementation for sparse matrices is also available.
§QR decomposition with column pivoting
The QR decomposition with column pivoting (Mat::col_piv_qr
) decomposes a matrix $A$ into
the product
$$AP^\top = QR,$$
where $P$ is a permutation matrix, $Q$ is a unitary matrix, and $R$ is an upper trapezoidal
matrix.
It is slower than the version with no pivoting, in exchange for being more numerically stable for rank-deficient matrices.
§Singular value decomposition
The SVD of a matrix $M$ of shape $(m, n)$ is a decomposition into three components $U$, $S$, and $V$, such that:
- $U$ has shape $(m, m)$ and is a unitary matrix,
- $V$ has shape $(n, n)$ and is a unitary matrix,
- $S$ has shape $(m, n)$ and is zero everywhere except the main diagonal, with nonnegative diagonal values in nonincreasing order,
- and finally:
$$M = U S V^H.$$
The SVD is provided in two forms: either the full matrices $U$ and $V$ are computed, using
Mat::svd
, or only their first $\min(m, n)$ columns are computed, using
Mat::thin_svd
.
If only the singular values (elements of $S$) are desired, they can be obtained in
nonincreasing order using Mat::singular_values
.
§Eigendecomposition
Note: The order of the eigenvalues is currently unspecified and may be changed in a future release.
The eigendecomposition of a square matrix $M$ of shape $(n, n)$ is a decomposition into two components $U$, $S$:
- $U$ has shape $(n, n)$ and is invertible,
- $S$ has shape $(n, n)$ and is a diagonal matrix,
- and finally:
$$M = U S U^{-1}.$$
If $M$ is hermitian, then $U$ can be made unitary ($U^{-1} = U^H$), and $S$ is real valued.
Depending on the domain of the input matrix and whether it is self-adjoint, multiple methods are provided to compute the eigendecomposition:
Mat::selfadjoint_eigendecomposition
can be used with either real or complex matrices, producing an eigendecomposition of the same type.Mat::eigendecomposition
can be used with either real or complex matrices, but the output complex type has to be specified.Mat::complex_eigendecomposition
can only be used with complex matrices, with the output having the same type.
If only the eigenvalues (elements of $S$) are desired, they can be obtained in
nonincreasing order using Mat::selfadjoint_eigenvalues
, Mat::eigenvalues
, or
Mat::complex_eigenvalues
, with the same conditions described above.
§Crate features
std
: enabled by default. Links with the standard library to enable additional features such as cpu feature detection at runtime.rayon
: enabled by default. Enables therayon
parallel backend and enables global parallelism by default.serde
: Enables serialization and deserialization ofMat
.npy
: Enables conversions to/from numpy’s matrix file format.perf-warn
: Produces performance warnings when matrix operations are called with suboptimal data layout.nightly
: Requires the nightly compiler. Enables experimental SIMD features such as AVX512.
Re-exports§
pub use col::Col;
pub use col::ColMut;
pub use col::ColRef;
pub use mat::Mat;
pub use mat::MatMut;
pub use mat::MatRef;
pub use row::Row;
pub use row::RowMut;
pub use row::RowRef;
pub use dyn_stack;
pub use reborrow;
Modules§
- Column vector type.
- Native complex floating point types whose real and imaginary parts are stored contiguously.
- Diagonal matrix type.
- io
std
De-serialization from common matrix file formats. - Linear algebra module.
- Matrix type.
- modulesDeprecatedRe-exports.
- Permutation matrices.
- faer prelude. Includes useful types and traits for solving linear systems.
- Row vector type.
- solversDeprecatedMatrix solvers and decompositions.
- Sparse data structures and algorithms. Sparse matrix data structures.
- stats
rand
Statistics-related utilities. - Various utilities for low level implementations in generic code.
Macros§
- Compare matrices for exact or approximate equality.
- Creates a
col::Col
containing the arguments. - Concatenates the matrices in each row horizontally, then concatenates the results vertically.
- Similar to the
dbg
macro, but takes a format spec as a first parameter. - Creates a
Mat
containing the arguments. - Creates a
row::Row
containing the arguments. - Used to undo the zipping by the
zipped!
macro. - Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.
Structs§
- Factor for matrix-scalar multiplication.
Enums§
- Whether a matrix should be implicitly conjugated when read or not.
- Parallelism strategy that can be passed to most of the routines in the library.
- Specifies whether the triangular lower or upper part of a matrix should be accessed.
Traits§
- Unstable trait containing the operations that a number type needs to implement.
- Trait for types that may be implicitly conjugated.
- Unstable core trait for describing how a scalar value may be split up into individual component.
- Trait for unsigned integers that can be indexed with.
- Unstable trait containing the operations that a real number type needs to implement.
- Trait for signed integers corresponding to the ones satisfying
Index
.
Functions§
- Causes functions that access global parallelism settings to panic.
- Gets the global parallelism settings.
- Returns a factor for matrix-scalar multiplication.
- Sets the global parallelism settings.